Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Wrap signatures onto several lines when function len is over a treshold #831

Open
wants to merge 42 commits into
base: master
Choose a base branch
from

Conversation

tristanlatr
Copy link
Contributor

@tristanlatr tristanlatr commented Oct 25, 2024

This change fixes #801 as well as introduce a rather a lot of refactoring and new ParsedDocstring features.

  • Parameters html are divided into .sig-param or .sig-symbol spans.
  • When the function is long enough (88 chars excluding the def and ending colon, this is hard coded) an extra CSS class .long-signature is added to the parent function-signature.
  • The first parameter 'cls' or 'self' of (class) methods is marked with the 'undocumented' CSS class, this way it's clearly not part of the API.
  • Add some CSS to expand the signature of long functions when they have the focus.
  • Refactor CSS rules for parameters tables to be more simpler and predictable with percentage values for smaller screens.
  • Remove ValueFormatter classes since they were only a hack to show HTML tags inside Signature.__str__(), which we don't need anymore because we're computing the representation ourselve.
  • Remove ParsedStanOnly class because we know have better alternatives.
  • Introduce ParsedDocstring.to_text() -> str.
  • ParsedDocstring.with_tag(Tag) -> ParsedDocstring.
  • ParsedDocstring.combine(list[ParsedDocsrting]) -> ParsedDocstring.
  • When a function has invalid parameters its rendered as (…) instead of confusing () - like it was a zero argument callable.

Examples:

  • Not wrapped because overloaded function never get wrapped.

Capture d’écran, le 2024-11-15 à 11 48 35

  • Wrapped because the function length is over 88 chars

Capture d’écran, le 2024-11-15 à 11 49 30

The way to get the old behaviour back is to use the following custom css:

.sig-param, .sig-symbol {
    display: initial !important;
    margin-left: 0 !important;
    padding-left: 0 !important;
}

…ill help to construct one parsed docstring from several parts.
We mimic the Signature.__str__ method for the implementation but instead of returning a str we return a ParsedDocstring, which is far more convenient.

This change fixes #801:
- Parameters html are divided into .sig-param spans.
- When the function is long enought an extra CSS class .expand-signature is added to the parent function-signature.
- The first parameter 'cls' or 'self' of (class) methods is marked with the 'undocumented' CSS class, this way it's clearly not part of the API.
- Add some CSS  to expand the signature of long functions when they have the focus only.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

Copy link

codecov bot commented Oct 25, 2024

Codecov Report

Attention: Patch coverage is 96.25000% with 9 lines in your changes missing coverage. Please review.

Project coverage is 92.85%. Comparing base (1c6478e) to head (a37b028).

Files with missing lines Patch % Lines
pydoctor/epydoc/markup/__init__.py 90.90% 6 Missing ⚠️
pydoctor/epydoc2stan.py 97.11% 2 Missing and 1 partial ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##           master     #831      +/-   ##
==========================================
+ Coverage   92.79%   92.85%   +0.05%     
==========================================
  Files          47       47              
  Lines        8468     8588     +120     
  Branches     1550     1578      +28     
==========================================
+ Hits         7858     7974     +116     
- Misses        350      353       +3     
- Partials      260      261       +1     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

This comment has been minimized.

… docstrings they only update the local to_stan() method dynamically.
…w parsed docstrings they only update the local to_stan() method dynamically."

This reverts commit eca5ced.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

2 similar comments

This comment has been minimized.

This comment has been minimized.

…s when overloads are overwhelming... This probably requires some more tweaks but it's still better than showing everything at once.

This comment has been minimized.

This comment has been minimized.

Fix some cyclic imports issue as a drive-by change: model.Documentable was uncessarly runtime imported inside restructuredtext and epydoc parsers.

This comment has been minimized.

@tristanlatr tristanlatr changed the title Signatures improvments Wrap signatures onto several lines when function len is over a treshold Nov 21, 2024
pydoctor/test/test_astbuilder.py Outdated Show resolved Hide resolved
pydoctor/epydoc/markup/__init__.py Outdated Show resolved Hide resolved
pydoctor/epydoc/markup/__init__.py Show resolved Hide resolved
pydoctor/themes/base/apidocs.css Outdated Show resolved Hide resolved
pydoctor/themes/base/apidocs.css Show resolved Hide resolved
pydoctor/epydoc/markup/__init__.py Outdated Show resolved Hide resolved
pydoctor/epydoc/markup/restructuredtext.py Outdated Show resolved Hide resolved
pydoctor/epydoc/markup/restructuredtext.py Outdated Show resolved Hide resolved
pydoctor/epydoc2stan.py Outdated Show resolved Hide resolved
pydoctor/templatewriter/pages/__init__.py Outdated Show resolved Hide resolved
pydoctor/epydoc2stan.py Outdated Show resolved Hide resolved
pydoctor/epydoc2stan.py Outdated Show resolved Hide resolved
@tristanlatr tristanlatr marked this pull request as ready for review December 13, 2024 18:30

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

1 similar comment

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

2 similar comments

This comment has been minimized.

This comment has been minimized.

README.rst Show resolved Hide resolved
Copy link

According to pydoctor_primer, this change doesn't affect pydoctor warnings on a corpus of open source code. ✅

@@ -997,7 +976,7 @@ def colorized_pyval_fallback(_: List[ParseError], doc:ParsedDocstring, __:model.
"""
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks like this docstring is wrong

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

HTML: Break function signature elements into multiple spans
1 participant